5 追蹤者

郵件 ¶

設定
基本用法
撰寫郵件內容
檔案附件
嵌入圖片
測試與偵錯
建立您自己的郵件解決方案

注意：本節仍在開發中。

Yii 支援電子郵件訊息的撰寫和發送。然而，框架核心僅提供內容撰寫功能和基本介面。實際的郵件發送機制應由擴展提供，因為不同的專案可能需要不同的實作方式，並且通常取決於外部服務和函式庫。

對於最常見的情況，您可以使用官方擴展 yii2-symfonymailer。

設定 ¶

郵件組件設定取決於您選擇的擴展。一般來說，您的應用程式設定應如下所示

return [
    //....
    'components' => [
        'mailer' => [
            'class' => 'yii\symfonymailer\Mailer',
            'useFileTransport' => false,
            'transport' => [
                'dsn' => 'smtp://user:pass@smtp.example.com:465',
            ],
        ],
    ],
];

基本用法 ¶

一旦設定了 mailer 組件，您可以使用以下程式碼發送電子郵件訊息

Yii::$app->mailer->compose()
    ->setFrom('from@domain.com')
    ->setTo('to@domain.com')
    ->setSubject('Message subject')
    ->setTextBody('Plain text content')
    ->setHtmlBody('<b>HTML content</b>')
    ->send();

在上面的範例中，方法 compose() 建立了一個郵件訊息的實例，然後對其進行填充並發送。如果需要，您可以在此過程中放入更複雜的邏輯

$message = Yii::$app->mailer->compose();
if (Yii::$app->user->isGuest) {
    $message->setFrom('from@domain.com');
} else {
    $message->setFrom(Yii::$app->user->identity->email);
}
$message->setTo(Yii::$app->params['adminEmail'])
    ->setSubject('Message subject')
    ->setTextBody('Plain text content')
    ->send();

注意：每個 mailer 擴展都包含 2 個主要類別：Mailer 和 Message。 Mailer 始終知道 Message 的類別名稱和具體資訊。請勿嘗試直接實例化 Message 物件 — 始終使用 compose() 方法。

您也可以一次發送多個訊息

$messages = [];
foreach ($users as $user) {
    $messages[] = Yii::$app->mailer->compose()
        // ...
        ->setTo($user->email);
}
Yii::$app->mailer->sendMultiple($messages);

某些特定的郵件擴展可能會從這種方法中受益，例如使用單一網路訊息等。

撰寫郵件內容 ¶

Yii 允許透過特殊的視圖檔案撰寫實際的郵件訊息內容。預設情況下，這些檔案應位於 @app/mail 路徑。

郵件視圖檔案內容範例

<?php
use yii\helpers\Html;
use yii\helpers\Url;

/* @var $this \yii\web\View view component instance */
/* @var $message \yii\mail\BaseMessage instance of newly created mail message */

?>
<h2>This message allows you to visit our site home page by one click</h2>
<?= Html::a('Go to home page', Url::home('http')) ?>

為了透過視圖檔案撰寫訊息內容，只需將視圖名稱傳遞給 compose() 方法

Yii::$app->mailer->compose('home-link') // a view rendering result becomes the message body here
    ->setFrom('from@domain.com')
    ->setTo('to@domain.com')
    ->setSubject('Message subject')
    ->send();

您可以將額外的視圖參數傳遞給 compose() 方法，這些參數將在視圖檔案內可用

Yii::$app->mailer->compose('greetings', [
    'user' => Yii::$app->user->identity,
    'advertisement' => $adContent,
]);

您可以為 HTML 和純文字訊息內容指定不同的視圖檔案

Yii::$app->mailer->compose([
    'html' => 'contact-html',
    'text' => 'contact-text',
]);

如果您將視圖名稱指定為純量字串，則其呈現結果將用作 HTML 正文，而純文字正文將透過從 HTML 正文中移除所有 HTML 實體來撰寫。

視圖呈現結果可以包裝在佈局中，佈局可以使用 yii\mail\BaseMailer::$htmlLayout 和 yii\mail\BaseMailer::$textLayout 進行設定。它的工作方式與常規 Web 應用程式中的佈局相同。佈局可用於設定郵件 CSS 樣式或其他共享內容

<?php
use yii\helpers\Html;

/* @var $this \yii\web\View view component instance */
/* @var $message \yii\mail\MessageInterface the message being composed */
/* @var $content string main view render result */
?>
<?php $this->beginPage() ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=<?= Yii::$app->charset ?>" />
    <style type="text/css">
        .heading {...}
        .list {...}
        .footer {...}
    </style>
    <?php $this->head() ?>
</head>
<body>
    <?php $this->beginBody() ?>
    <?= $content ?>
    <div class="footer">With kind regards, <?= Yii::$app->name ?> team</div>
    <?php $this->endBody() ?>
</body>
</html>
<?php $this->endPage() ?>

檔案附件 ¶

您可以使用方法 attach() 和 attachContent() 將附件新增到訊息中

$message = Yii::$app->mailer->compose();

// attach file from local file system
$message->attach('/path/to/source/file.pdf');

// create attachment on-the-fly
$message->attachContent('Attachment content', ['fileName' => 'attach.txt', 'contentType' => 'text/plain']);

嵌入圖片 ¶

您可以使用 embed() 方法將圖片嵌入到訊息內容中。此方法傳回附件 ID，然後應在 img 標籤中使用該 ID。當透過視圖檔案撰寫訊息內容時，此方法易於使用

Yii::$app->mailer->compose('embed-email', ['imageFileName' => '/path/to/image.jpg'])
    // ...
    ->send();

然後在視圖檔案內，您可以使用以下程式碼

<img src="<?= $message->embed($imageFileName); ?>">

測試與偵錯 ¶

開發人員通常需要檢查應用程式實際發送了哪些電子郵件、它們的內容等等。Yii 透過 yii\mail\BaseMailer::useFileTransport 授予了這種能力。如果啟用此選項，它將強制將郵件訊息資料儲存到本機檔案中，而不是進行常規發送。這些檔案將儲存在 yii\mail\BaseMailer::fileTransportPath 下，預設為 @runtime/mail。

注意：您可以將訊息儲存到檔案中或將其發送到實際收件人，但不能同時執行這兩者。

郵件訊息檔案可以使用常規文字檔案編輯器開啟，因此您可以瀏覽實際的訊息標頭、內容等等。在偵錯應用程式或執行單元測試時，此機制可能會證明其價值。

注意：郵件訊息檔案內容是透過 \yii\mail\MessageInterface::toString() 撰寫的，因此它取決於您在應用程式中使用的實際郵件擴展。

建立您自己的郵件解決方案 ¶

為了建立您自己的自訂郵件解決方案，您需要建立 2 個類別：一個用於 Mailer，另一個用於 Message。您可以使用 yii\mail\BaseMailer 和 yii\mail\BaseMessage 作為您的解決方案的基底類別。這些類別已經包含本指南中描述的基本邏輯。但是，它們的使用不是強制性的，實作 yii\mail\MailerInterface 和 yii\mail\MessageInterface 介面就足夠了。然後您需要實作所有抽象方法來建構您的解決方案。

國際化

回到頂部

效能調校

發現錯字或您認為此頁面需要改進？
在 github 上編輯它 !